home *** CD-ROM | disk | FTP | other *** search
/ Network Support Library / RoseWare - Network Support Library.iso / btrieve / btr61m.exe / 12AA.TXT < prev    next >
Text File  |  1993-07-16  |  33KB  |  947 lines
  1. APPENDIX A      DESCRIPTION FILES
  2.  
  3. A description file is an ASCII file containing
  4. information that the Maintenance utility commands
  5. CREATE, INDEX, and SINDEX need to perform their
  6. operations.  Description files contain one or more
  7. elements.  An element consists of a keyword, followed
  8. by an equal sign (=), followed by a value (with no
  9. space).  Each element in the description file
  10. corresponds to a particular characteristic of a Btrieve
  11. file or key definition.
  12.  
  13. The sections in this appendix discuss the following
  14. topics:
  15.  
  16. o Rules for Description Files
  17. o Description File Example
  18. o Description File Elements
  19.  
  20.  
  21. Rules for Description Files
  22.  
  23. Use the following rules when creating a description
  24. file.
  25.  
  26. o Enter elements in lowercase, as in the following
  27.   example:
  28.  
  29.   type=flo
  30.  
  31. o Separate elements from each other with a separator
  32.   (blank space, tab, or carriage return/line feed), as
  33.   in the following example:
  34.  
  35.   record=4000
  36.   key=24
  37.  
  38. o Specify the description file elements in the proper
  39.   order.  Table A-1 presents the elements in the
  40.   appropriate order.
  41.  
  42.    NOTE:  The order of the elements required for the
  43.    CREATE, INDEX, and SINDEX commands is the same.
  44.    However, these commands do not all require the same
  45.    elements.
  46.  
  47. o Address all element dependencies.  For example,
  48.   consider the following Null Key element:
  49.  
  50.   null=y
  51.  
  52.   If you specify this element in the description file,
  53.   you must also include the Null Key Value element.
  54.  
  55. o Define as many keys as you specify with the Key Count
  56.   element.  The following example specifies 12 keys for
  57.   the file:
  58.  
  59.   key=12
  60.  
  61.   In this case, you must define 12 keys in the
  62.   description file, each consisting of one or more
  63.   segments.
  64.  
  65. o For a key with multiple segments, you must define the
  66.   following elements for each key segment:
  67.  
  68.   - Key Position
  69.   - Key Length
  70.   - Duplicate Key Values
  71.   - Modifiable Key Values
  72.   - Key Type
  73.   - Alternate Collating Sequence
  74.  
  75.   The Descending Sort Order element is optional for
  76.   each segment.
  77.  
  78. o If any key in the file uses an alternate collating
  79.   sequence, include either an alternate collating
  80.   sequence filename or a country ID and code page ID.
  81.   You can include this information as either the last
  82.   element of the key segment or the last element in the
  83.   description file.
  84.  
  85. o If a description file element is optional, you can
  86.   omit it from the description file.
  87.  
  88. o Make sure the description file contains no text
  89.   formatting characters.  Some word processors embed
  90.   formatting characters in a text file.
  91.  
  92.  
  93. Description File Example
  94.  
  95. The sample description file shown in Figures A-1, A-2,
  96. and A-3 creates a Btrieve file.  This Btrieve file has
  97. a page size of 512 bytes and 2 keys.  The fixed-length
  98. portion of the record is 98 bytes long.  The file
  99. allows variable-length records but does not use blank
  100. truncation.
  101.  
  102. The file uses data compression, allows for
  103. Variable-tail Allocation Tables (VATs), and has the
  104. free space threshold set to 20 percent.  Btrieve
  105. preallocates 100 pages, or 51,200 bytes, when it
  106. creates the file.  The file has two keys:  Key 0 and
  107. Key 1.  Key 0 is a segmented key with two segments.
  108.  
  109. Figure A-1
  110. Sample Description File Using Alternate
  111. Collating Sequence Filename
  112.  
  113. ---------------------------------------------------------------------------
  114.  record=98 variable=y truncate=n compress=y  ---+
  115.  key=2 page=512 allocation=100 replace=n    | File Specifications
  116.  fthreshold=20 huge=y                        ---+
  117.  
  118.  position=1 length=5 duplicates=y            ---+ Key 0
  119.  modifiable=n type=string alternate=y           | Segment 1
  120.  null=y value=20 segment=y                   ---+
  121.  
  122.  position=6 length=10 duplicates=y           ---+ Key 0
  123.  modifiable=n type=string alternate=y           | Segment 2
  124.  null=y value=20 segment=n                   ---+
  125.  
  126.  position=16 length=2 duplicates=n           ---+ Key 1
  127.  modifiable=y type=numeric descending=y         |
  128.  alternate null=n segment=n                  ---+
  129.  
  130.  name=path/upper.alt
  131. --------------------------------------------------------------------------
  132.  
  133. In Figure A-1, an alternate collating sequence
  134. filename (UPPER.ALT) is specified for Key 0.
  135.  
  136. If you specify y for the Alternate Collating Sequence
  137. element for a key, you must supply an alternate
  138. collating sequence filename or a country ID and code
  139. page ID.
  140.  
  141. Figure A-2
  142. Sample Description File Using Alternate
  143. Collating Sequence ID
  144.  
  145.  
  146. ---------------------------------------------------------------------------
  147.  record=98 variable=y truncate=n compress=y  ---+
  148.  key=2 page=512 allocation=100 replace=n    | File Specifications
  149.  fthreshold=20 huge=y                        ---+
  150.  
  151.  position=1 length=5 duplicates=y            ---+ Key 0
  152.  modifiable=n type=string alternate=y           | Segment 1
  153.  null=y value=20 segment=y                   ---+
  154.  
  155.  position=6 length=10 duplicates=y           ---+ Key 0
  156.  modifiable=n type=string alternate=y           | Segment 2
  157.  null=y value=20 segment=n                   ---+
  158.  
  159.  position=16 length=2 duplicates=n           ---+ Key 1
  160.  modifiable=y type=numeric descending=y         |
  161.  alternate null=n segment=n                  ---+
  162.  
  163.  countryid=-1   codepageid=-1
  164. --------------------------------------------------------------------------
  165.  
  166. In Figure A-2, a country ID and code page ID are
  167. specified (countryid=-1 and codepageid=-1).  If you
  168. specify the name=sequenceFile element (or the
  169. countryid=nnn and codepageid=nnn elements) at the end
  170. of the description file, Btrieve uses it as the
  171. default alternate collating sequence.
  172.  
  173. That is, if you specify alternate=y for a given key
  174. but do not include a name=sequenceFile element (or the
  175. countryid=nnn and codepageid=nnn elements) for that
  176. key, Btrieve uses the name=sequenceFile element (or
  177. the countryid=nnn and codepageid=nnn elements)
  178. specified at the end of the description file.
  179.  
  180. Figure A-3
  181. Sample Description File Using Alternate
  182. Collating Sequence Filename on a
  183. File Segment
  184.  
  185. ---------------------------------------------------------------------------
  186.  record=98 variable=y truncate=n compress=y    ---+
  187.  key=2 page=512 allocation=100 replace=n      | File Specifications
  188.  fthreshold=20 huge=y                          ---+
  189.  
  190.  position=1 length=5 duplicates=y              ---+ Key 0
  191.  modifiable=n type=string alternate=y             | Segment 1
  192.  null=y value=20 segment=y name=path/lower.alt ---+
  193.  
  194.  position=6 length=10 duplicates=y             ---+ Key 0
  195.  modifiable=n type=string alternate=y             | Segment 2
  196.  null=y value=20 segment=n name=path/lower.alt ---+
  197.  
  198.  position=16 length=2 duplicates=n             ---+ Key 1
  199.  modifiable=y type=numeric descending=y           |
  200.  alternate null=n segment=n                       |
  201.  name=path/upper.alt                   ---+
  202. --------------------------------------------------------------------------
  203.  
  204. In Figure A-3, a different alternate collating
  205. sequence filename is specified for Key 0 and Key 1.
  206. If you want to use different alternate collating
  207. sequences for different keys, you must specify the
  208. name=sequenceFile element (or the countryid=nnn and
  209. codepageid=nnn elements) for each key that uses a
  210. different alternate collating sequence.  Different
  211. segments of the same key cannot have different
  212. alternate collating sequences.
  213.  
  214. You can specify only one alternate collating sequence
  215. per key, and you must provide an alternate collating
  216. sequence filename (or values for the countryid=nnn and
  217. codepageid=nnn elements) for each segment of the key.
  218. The filename for the name=sequenceFile element (or
  219. values for the countryid=nnn and codepageid=nnn
  220. elements) must be the same for each segment.  In
  221. Figure A-3, the filename specified for each segment in
  222. Key 0 is LOWER.ALT.  The filename specified for Key 1
  223. is UPPER.ALT.
  224.  
  225.  
  226. Description File Elements
  227.  
  228. Table A-1 lists the description file elements in the
  229. order in which they must appear in the description
  230. file.  For each element, Table A-1 specifies the
  231. required format, the range of acceptable values, and
  232. the associated commands.  An asterisk (*) after the
  233. element name indicates that the element is optional.
  234. Descriptions of the individual elements follow the
  235. table.
  236.  
  237. Table A-1
  238. Summary of
  239. Description File
  240. Elements
  241. --------------------------------------------------------------------------
  242. Element              Format           Range          Command
  243.  
  244. Record Length        record=nnnn      4-4,088        CREATE
  245. Variable-Length
  246.   Records            variable=<y|n>   N/A            CREATE
  247. Reserved
  248.   Duplicate Pointer* dupkey=<nnn>     1-119          CREATE
  249. Blank Truncation*    truncate=<y|n>   N/A            CREATE
  250. Data Compression*    compress=<y|n>   N/A            CREATE
  251. Key Count            key=nnn          0-118          CREATE
  252. Page Size            page=nnnn        512-4,096      CREATE
  253. Page Preallocation*  allocation=nnnnn 1-65,535       CREATE
  254. Replace Existing
  255.   File*              replace=<y|n>    N/A            CREATE
  256. Include Data*        data=<y|n>       N/A            CREATE
  257. Free Space
  258.   Threshold*         fthreshold=<10|20|30>     N/A   CREATE
  259. Variable-Tail
  260.   Allocation Tables
  261.   (VATs)             huge=<y|n>       N/A            CREATE
  262. Balanced Index*      balance=<y|n>    N/A            CREATE
  263. Key Position         position=nnnn    1-4,088        CREATE, INDEX, SINDEX
  264. Key Length           length=nnn       key type limit CREATE, INDEX, SINDEX
  265. Duplicate Key Values duplicates=<y|n> N/A            CREATE, INDEX, SINDEX
  266. Modifiable Key Values modifiable=<y|n> N/A           CREATE, INDEX, SINDEX
  267. Key Type             type=validBtrieveKeyType  N/A   CREATE, INDEX, SINDEX
  268. Descending Sort
  269.   Order*             descending=<y|n> N/A            CREATE, INDEX, SINDEX
  270. Alternate Collating
  271.   Sequence*          alternate=<y|n>  N/A            CREATE, INDEX, SINDEX
  272. Case-Insensitive
  273.   Key*               caseinsensitive=<y|n>     N/A   CREATE, INDEX, SINDEX
  274. Repeating
  275.   Duplicates*        repeatdup=<y|n>  N/A            CREATE, SINDEX
  276. Manual Key*          manual=<y|n>     N/A            CREATE, INDEX, SINDEX
  277. Null Key             null=<y|n>       N/A            CREATE, INDEX, SINDEX
  278. Null Key Value       value=nn         1-byte hex     CREATE, INDEX, SINDEX
  279. Segmented Key        segment=<y|n>    N/A            CREATE, INDEX, SINDEX
  280. Alternate Collating
  281.   Sequence Filename                                  CREATE, INDEX, SINDEX
  282.   /ID                name=sequenceFile
  283.                      or
  284.                      countryid=nnn
  285.                      and codepageid=nnn   valid path or
  286.                                           values valid
  287.                                           to operating
  288.                                           system or -1
  289.                                           (default)
  290. --------------------------------------------------------------------------
  291.  
  292. Record Length
  293.  
  294. Format: record=nnnn
  295. Range: 4 through 4,088 bytes
  296. Command: CREATE
  297.  
  298. The Record Length element defines the logical data
  299. record length in bytes.  For fixed-length records,
  300. this value should correspond to the length of the data
  301. buffer parameter that performs operations on the
  302. file.  For variable-length records, this value should
  303. correspond to the fixed-length portion of the record.
  304.  
  305. The data record length must be at least 4 bytes and
  306. must be large enough to contain all the keys defined
  307. for the file.  The record length (including its
  308. duplicate key overhead and usage count overhead) plus
  309. 6 bytes must not exceed the file's page size.
  310.  
  311.  
  312. Variable-Length Records
  313.  
  314. Format: variable=<y|n>
  315. Range: Not applicable
  316. Command: CREATE
  317.  
  318. The Variable-Length Records element specifies whether
  319. the file will contain variable-length records.  If a
  320. record is variable length, the maximum fixed-length
  321. record is decreased by 4 bytes.  Specify y if you want
  322. the file to allow variable-length records; otherwise,
  323. specify n.
  324.  
  325.  
  326. Reserved Duplicate Pointer
  327.  
  328. Format: dupkey=nnn
  329. Range: 1 through 119
  330. Command: CREATE
  331.  
  332. The Reserved Duplicate Pointer element is optional.
  333. It specifies the number of duplicate key pointers to
  334. preallocate for the file when it is created.  Each
  335. reserved duplicate pointer adds 8 bytes of extra
  336. storage space to the fixed record length.  These
  337. reserved pointers can be used when keys that allow
  338. duplicates are added after the file is created and if
  339. you do not specify y for the Repeating Duplicates
  340. element.
  341.  
  342.  
  343. Blank Truncation
  344.  
  345. Format: truncate=<y|n>
  346. Range: Not applicable
  347. Command: CREATE
  348.  
  349. The Blank Truncation element is optional.  It
  350. specifies whether Btrieve performs blank truncation on
  351. variable-length records.  The truncate element has an
  352. effect only if you specify y for the Variable-Length
  353. Records element.  Specify y if you want Btrieve to use
  354. blank truncation.  Otherwise, either specify n or omit
  355. this element from your description file.
  356.  
  357.  
  358. Data Compression
  359.  
  360. Format: compress=<y|n>
  361. Range: Not applicable
  362. Command: CREATE
  363.  
  364. The Data Compression element is optional.  It
  365. specifies whether Btrieve performs data compression on
  366. records that are inserted into the file.  Specify y if
  367. you want Btrieve to perform data compression.
  368. Otherwise, either specify n or omit this element from
  369. your description file.
  370.  
  371.  
  372. Key Count
  373.  
  374. Format: key=nnn
  375. Range: 0 through 118 (see Table A-2)
  376. Command: CREATE
  377.  
  378. The Key Count element specifies the number of keys to
  379. be defined in the file.  If you specify a value of 0
  380. for this element, Btrieve creates a data-only file.
  381. If you specify a value greater than 0, Btrieve creates
  382. either a standard file or a key-only file, depending
  383. on the value you specify for the Include Data
  384. element.  The file╒s page size limits the amount of
  385. key segments a file can have.  Table A-2 shows the
  386. maximum key count values for each possible page size.
  387. This value represents the number of key segments, not
  388. the number of keys.  There may actually be more
  389. segment definitions than the key count.  For example,
  390. assume a file contains three keys:  key 0 has 2
  391. segments, key 1 has 4 segments, and key 2 has 2
  392. segments.  In this example, the file has a page size
  393. of 512, the value specified for the Key Count element
  394. is 3, and the maximum number of key segments is 8.
  395.  
  396. Table A-2 Key Segment Count Values
  397.  
  398. Page Size (in bytes)     Maximum
  399.                          Number of Key Segments
  400.  
  401.   512                      8
  402. 1,024                     23
  403. 1,536                     24
  404. 2,048-3,584               54
  405. 4,096                    119
  406.  
  407.  
  408. Page Size
  409.  
  410. Format: page=nnnn
  411. Range: 512 through 4,096 bytes
  412. Command: CREATE
  413.  
  414. The Page Size element specifies the physical page size
  415. (in bytes) for the file.  You can specify any multiple
  416. of 512, up to 4,096.
  417.  
  418. SUGGESTION:  For optimum performance, set the page size
  419. to 512, 1,024, 2,048, or 4,096 bytes.
  420.  
  421.  
  422. Page Preallocation
  423.  
  424. Format: allocation=nnnnn
  425. Range: 1 through 65,535
  426. Command: CREATE
  427.  
  428. The Page Preallocation element is optional.  It
  429. specifies the number of pages to preallocate to the
  430. file.  If you do not want to preallocate any pages,
  431. either specify n or omit this element from your
  432. description file.
  433.  
  434.  
  435. Replace Existing File
  436.  
  437. Format: replace=<y|n>
  438. Range: Not applicable
  439. Command: CREATE
  440.  
  441. The Replace Existing File element is optional.  If you
  442. do not want to create a new, empty file over an
  443. existing Btrieve file of the same name, specify n.  If
  444. you want to replace an existing Btrieve file with a
  445. new, empty file of the same name, either specify y or
  446. omit this element from your description file.
  447.  
  448.  
  449. Include Data
  450.  
  451. Format: data=<y|n>
  452. Range: Not applicable
  453. Command: CREATE
  454.  
  455. The Include Data element is optional.  It specifies
  456. the file type that the utility creates.  To create a
  457. key-only file, specify n.  To create a standard file,
  458. either specify y or omit the element from the
  459. description file.  To create a data-only file, specify
  460. y and set the Key Count element to 0.
  461.  
  462.  
  463. Free Space Threshold
  464.  
  465. Format: fthreshold=<10|20|30>
  466. Range: Not applicable
  467. Command: CREATE
  468.  
  469. Btrieve stores the variable-length portions of records
  470. on their own pages (called variable pages), separate
  471. from the fixed-length portion of the record (which is
  472. stored on a data page).  Btrieve maintains the Free
  473. Space List for variable pages.  The Free Space List
  474. indicates which variable pages contain the same or
  475. more free space than that specified by the Free Space
  476. Threshold file specification.
  477.  
  478. You can specify a value for the Free Space Threshold
  479. element when you create the file.  This value is
  480. expressed as a percentage and tells Btrieve how much
  481. free space must remain on a variable page in order for
  482. that page to appear on the Free Space List.  When
  483. Btrieve adds new variable-length records to the file,
  484. it uses pages in the Free Space List before using new
  485. variable pages.  After each Insert, Update, or Delete
  486. operation, Btrieve rechecks the remaining space on the
  487. affected variable page to see if it is still above the
  488. threshold to qualify for the Free Space List.  The
  489. free space threshold feature provides a means of
  490. reducing the fragmentation of variable-length records
  491. across several pages.  A higher free space threshold
  492. reduces fragmentation at the cost of requiring more
  493. disk space for the file.
  494.  
  495. You can specify any two-digit number for this element,
  496. and the utility rounds it to 10, 20, or 30.
  497. Btrieve uses a default free space threshold of 5 percent
  498. if either of the following is true:
  499.  
  500. o You specify a value less than 10.
  501. o You do not specify a value here but have specified y
  502.   for the Variable-Length Records element.
  503.  
  504. NOTE:  If the Btrieve file does not allow
  505. variable-length records, do not include this element
  506. in the description file.
  507.  
  508.  
  509. Variable-Tail Allocation Tables (VATs)
  510.  
  511. Format: huge=<y|n>
  512. Range: Not applicable
  513. Command: CREATE
  514.  
  515. The Variable-tail Allocation Tables (VATs) element is
  516. optional.  Btrieve v6.1 allows an application to
  517. create Btrieve files that contain structures called
  518. Variable-tail Allocation Tables (VATs), which are
  519. implemented as linked lists.  To accelerate random
  520. access to portions of records, Btrieve uses VATs with
  521. each record.  VATs are also helpful in files using
  522. data compression to limit the size of the compression
  523. buffer used by Btrieve.  If you want to create a file
  524. that uses VATs, specify y.  Otherwise, either specify
  525. n or omit this element from your description file.
  526. For more information about VATs, refer to the Btrieve
  527. Programmer's Manual.
  528.  
  529.  
  530. Balanced Index
  531.  
  532. Format: balance=<y|n>
  533. Range: Not applicable
  534. Commands: CREATE
  535.  
  536. The Balanced Index element is optional.  This feature
  537. allows you to use index balancing.  With index
  538. balancing, Btrieve looks for available space in
  539. sibling index pages each time an index page becomes
  540. full and then rotates values from the full page into
  541. the pages with space available.  Index balancing
  542. increases index page utilization, results in fewer
  543. pages, and produces an even distribution of keys among
  544. nodes on the same level, thus enhancing performance
  545. during Get operations.  However, the use of this
  546. feature also means that Btrieve requires extra time to
  547. examine more index pages and may require more disk I/O
  548. during Insert, Update, and Delete operations.
  549.  
  550. NOTE:  You can specify index balancing on a
  551. file-by-file basis when the file is created.  When you
  552. specify index balancing for a specific file, Btrieve
  553. will always balance that file's keys.  You can also
  554. turn index balancing on and off for files that are not
  555. flagged as balanced by specifying Yes to the Perform
  556. Index Balancing configuration option in the Setup
  557. utility.
  558.  
  559. To use index balancing, specify y.  Otherwise, either
  560. specify n or omit this element from the description
  561. file.
  562.  
  563.  
  564. Key Position
  565.  
  566. Format: position=nnnn
  567. Range: 1 through value specified for Record Length element (up to
  568.        4,088)
  569. Commands: CREATE, INDEX, SINDEX
  570.  
  571. The Key Position element indicates the position of the
  572. key segment in the record.  The key position value
  573. must be at least 1 and cannot exceed the value you
  574. specified for the Record Length element.
  575.  
  576.  
  577. Key Length
  578.  
  579. Format:  length=nnn
  580. Range:  1 through limit determined by key type
  581. Commands:  CREATE, INDEX, SINDEX
  582.  
  583. The Key Length element defines the length of the key or key
  584. segment field.  The value you specify here cannot
  585. exceed the limit dictated by the key type, which the
  586. Key Type element specifies.  The key length must be an
  587. even number if the key is a binary key type.  The
  588. total of the key's length and starting position cannot
  589. exceed the file's defined record length.
  590.  
  591.  
  592. Duplicate Key Values
  593.  
  594. Format: duplicates=<y|n>
  595. Range: Not applicable
  596. Commands: CREATE, INDEX, SINDEX
  597.  
  598. The Duplicate Key Values element specifies whether
  599. more than one record in the file can contain the same
  600. value for this key field.  Specify y if you want to
  601. allow duplicate values for the key field; otherwise,
  602. specify n.
  603.  
  604. NOTE:  If you define duplicate key values for one
  605. segment of a segmented key, you must define duplicate
  606. key values for every segment of that key.  For a
  607. segmented key that does not allow duplicates, the
  608. segments may contain duplicates between multiple
  609. records only if the key value is unique for each
  610. record.
  611.  
  612.  
  613. Modifiable Key Values
  614.  
  615. Format: modifiable=<y|n>
  616. Range: Not applicable
  617. Commands: CREATE, INDEX, SINDEX
  618.  
  619. The Modifiable Key Values element specifies whether
  620. the key value can be modified during an Update
  621. operation.  Specify y if you want the values for this
  622. key to be modifiable; otherwise, specify n.
  623.  
  624. NOTE:  If you define modifiable key values for one
  625. segment of a segmented key, you must define modifiable
  626. key values for every segment of that key because the
  627. key, as a whole, is modifiable.
  628.  
  629.  
  630. Key Type
  631.  
  632. Format: type=validBtrieveKeyType
  633. Range: Not applicable
  634. Commands: CREATE, INDEX, SINDEX
  635.  
  636. The Key Type element specifies the Btrieve data type
  637. for the key.  This element determines how Btrieve will
  638. sort the bytes specified for this key segment.
  639. Btrieve does not perform any validation on the data
  640. inserted.  You can specify the entire word (as in
  641. float) or just the first three letters of the word (as
  642. in flo for float).  The Btrieve key types are as
  643. follows:  autoinc integer string bfloat
  644. logicaltimedatelstringunsigned binary
  645. decimalmoneyzstring floatnumericsign trailing separate
  646.  
  647. NOTE:  STS (sign trailing separate) is a COBOL data
  648. type.  It is basically a numeric data type,
  649. represented as an ASCII string.  STS is right
  650. justified and padded with leading ASCII zeros, and it
  651. has the sign byte at the end.
  652.  
  653.  
  654. Descending Sort Order
  655.  
  656. Format: descending=<y|n>
  657. Range: Not applicable
  658. Commands: CREATE, INDEX, SINDEX
  659.  
  660. The Descending Sort Order element is optional.  It
  661. specifies whether Btrieve will collate the index or
  662. index segment in descending order.  Specify y if you
  663. want Btrieve to collate the key values in descending
  664. order.  If you want Btrieve to collate the index in
  665. ascending order, either specify n or omit this element
  666. from the description file.
  667.  
  668.  
  669. Alternate Collating Sequence
  670.  
  671. Format: alternate=<y|n>
  672. Range: Not applicable
  673. Commands: CREATE, INDEX, SINDEX
  674.  
  675. The Alternate Collating Sequence element is optional.
  676. This element allows you to specify one or more
  677. alternate collating sequences for a given file.  An
  678. alternate collating sequence specifies whether Btrieve
  679. will sort a key by a collating sequence other than the
  680. standard ASCII sequence.
  681.  
  682. You can specify a different alternate collating
  683. sequence for each key.  However, each segment of the
  684. key can have only one alternate collating sequence.
  685. Alternate collating sequences are valid only for
  686. string, lstring, and zstring key types.  If you want
  687. the key to take advantage of an alternate collating
  688. sequence, specify y.  Otherwise, either specify n or
  689. omit this element from the description file.
  690.  
  691. When using a description file to create an additional
  692. index for an existing Btrieve file, if you want the
  693. index to use an alternate collating sequence file
  694. other than the first one in the Btrieve file, specify
  695. alternate=y and caseinsensitive=y.
  696.  
  697. If you specify alternate=y and caseinsensitive=n and
  698. use an alternate collating sequence file other than
  699. the first one in the Btrieve file, the index will not
  700. be created.
  701.  
  702.  
  703. Case-Insensitive Key
  704.  
  705. Format: caseinsensitive=<y|n>
  706. Range: Not applicable
  707. Commands: CREATE, INDEX, SINDEX
  708.  
  709. The Case-Insensitive Key element is optional.  It
  710. specifies that the key (or key segment) you are
  711. defining is case insensitive.  You can specify this
  712. key element only for keys that are of type string,
  713. zstring, or lstring.
  714.  
  715. By default, Btrieve is case sensitive when sorting key
  716. strings; that is, it sorts string key values based on
  717. whether the letters are uppercase or lowercase.
  718. Btrieve sorts the values by placing the uppercase value
  719. first, followed by the lowercase value.  For example,
  720. key values starting with A would appear before those
  721. starting with a in the index.  Case sensitivity,
  722. however, does not apply if Btrieve sorts a key
  723. according to the collating sequence specified with the
  724. Alternate Collating Sequence element.
  725.  
  726. To specify that Btrieve ignore case when sorting the
  727. key value, specify y for this element.  Otherwise,
  728. either specify n or omit this element from the
  729. description file.
  730.  
  731.  
  732. Repeating Duplicates
  733.  
  734. Format: repeatdup=<y|n>
  735. Range: Not applicable
  736. Commands: CREATE, INDEX, SINDEX
  737.  
  738. Btrieve uses two methods for storing duplicatable keys
  739. internally.  The keys are stored as either
  740. linked-duplicatable keys or repeating-duplicatable
  741. keys.
  742.  
  743. o Linked-duplicatable key-In a Btrieve v6.1 file,
  744.   Btrieve stores duplicatable keys as
  745.   linked-duplicatable keys by default on a Create
  746.   operation.  (On a Create Index operation, Btrieve
  747.   uses linked-duplicatable keys if they are available;
  748.   otherwise, it uses repeating-duplicatable keys, as
  749.   explained in the following section.) Using this
  750.   method, Btrieve stores the key extracted from the
  751.   first record of a duplicatable key on an index page.
  752.  
  753.   Other records with keys containing duplicate values
  754.   are stored in the form of a linked list, with
  755.   pointers at the end of each record in a data page
  756.   pointing to the next and the previous records that
  757.   have the same duplicate key values.
  758.  
  759. o Repeating-duplicatable key-If no room is available
  760.   to create a linked-duplicatable key (that is, if no
  761.   duplicate pointers were reserved at file creation, or
  762.   if no index has been dropped to free existing
  763.   pointers), Btrieve stores duplicatable keys as
  764.   repeating-duplicatable keys.    Using this method,
  765.   Btrieve stores every key value of a
  766.   repeating-duplicatable key both in a data page and in
  767.   an index page.
  768.  
  769. NOTE:  Key-only files always use
  770. repeating-duplicatable keys because the key-only files
  771. use only the index pages and not the data pages.
  772.  
  773. Specify y to create repeating-duplicatable keys.
  774. Otherwise, either specify n or omit this element from
  775. the description file.
  776.  
  777. NOTE:  For a segmented key, all segments must have the
  778. same repeatdup=y/n specification.  For a nonsegmented
  779. key, if you specify repeatdup=y, you must also specify
  780. duplicate=y.
  781.  
  782.  
  783. Manual Key
  784.  
  785. Format: manual=<y|n>
  786. Range: Not applicable
  787. Commands: CREATE, INDEX, SINDEX
  788.  
  789. The Manual Key element is optional.  It specifies that
  790. the key or key segment you are defining is manual.  A
  791. manual key is a modified form of the null key and can
  792. be used to exclude particular records from the index.
  793. Manual keys have all the attributes of a null key with
  794. one exception:  in a manual key, if every byte of one
  795. segment of the key contains the null value, Btrieve
  796. excludes the key from the index even if other segments
  797. do not contain this null value.
  798.  
  799. If you define one segment of a key as a manual a null
  800. value for that segment, and you must define all other
  801. segments of that key as manual.  However, Btrieve
  802. allows you to define different null values for
  803. different segments in a segmented key.
  804.  
  805. To create a manual key or key segment, specify y;
  806. otherwise, specify n or omit this element from your
  807. description file.
  808.  
  809. NOTE:  The Btrieve Programmer's Manual refers to manual
  810. keys as "any-segment null keys."
  811.  
  812.  
  813. Null Key
  814.  
  815. Format: null=<y|n>
  816. Range: Not applicable
  817. Commands: CREATE, INDEX, SINDEX
  818.  
  819. The Null Key element specifies whether the key you are
  820. defining has a null value.  You can include the Null
  821. Key element in a description file for the INDEX
  822. command.  However, to maintain consistent formats for
  823. the CREATE, INDEX, and SINDEX description files, INDEX
  824. disregards any null value you specify.
  825.  
  826. If you define a null value for one segment of a
  827. segmented key, you must define a null value for every
  828. segment of that key.  However, Btrieve allows you to
  829. define different null values for different segments in
  830. a segmented key.
  831.  
  832. Specify y if you want to define a null value for this
  833. key.  Otherwise, specify n.
  834.  
  835. NOTE: The Btrieve Programmer's Manual refers to null
  836. keys as "all-segment null keys."
  837.  
  838.  
  839. Null Key Value
  840.  
  841. Format: value=nn
  842. Range: Any 1-byte hexadecimal value
  843. Commands: CREATE, INDEX, SINDEX
  844.  
  845. The Null Key Value element specifies the null
  846. character value (in hexadecimal) for the key.  Typical
  847. null values are 20 hexadecimal (blank) and 0
  848. hexadecimal (binary zero).  Include this element only
  849. if you defined the key as allowing null values.  If
  850. you specify n for both the Null Key element and the
  851. Manual Key element, the Null Key Value element is not
  852. required in the description file.
  853.  
  854.  
  855. Segmented Key
  856.  
  857. Format: segment=<y|n>
  858. Range: Not applicable
  859. Commands: CREATE, INDEX, SINDEX
  860.  
  861. The Segmented Key element specifies whether the key
  862. you are defining has any more segments.  Specify y if
  863. the key has another segment.  Specify n if you are
  864. defining either a nonsegmented key or the last segment
  865. of a segmented key.
  866.  
  867.  
  868. Alternate Collating Sequence Filename/ID
  869. Format: name=sequenceFile or countryid=nnn
  870.         codepageid=nnn
  871. Range:  Any valid, fully qualified pathname; or a valid
  872.         country ID and code page ID; or -1 (the
  873.         default)
  874. Commands: CREATE, INDEX, SINDEX
  875.  
  876. The Alternate Collating Sequence Filename/ID element
  877. specifies the pathname of the file that contains an
  878. alternate collating sequence for the file you are
  879. creating.  You can include up to 256 bytes of
  880. directory levels in the pathname (plus the filename).
  881. If you specified n for the Alternate Collating
  882. Sequence element for every key, do not include this
  883. element in your description file.
  884.  
  885. If you specified y for the Alternate Collating
  886. Sequence element for a key, you must supply either an
  887. alternate collating sequence filename or a country ID
  888. and a code page ID.  If you want all the keys in the
  889. file to use the same alternate collating sequence
  890. filename, you can either specify this element as the
  891. last element in the description file or specify the
  892. alternate collating sequence name for each key.  If
  893. you want to use different alternate collating
  894. sequences, you must specify this element for each key
  895. that uses an alternate collating sequence.  You can
  896. specify only one alternate collating sequence per key,
  897. and each segment of the key should have an alternate=
  898. and name= pair.
  899.  
  900. To use an alternate collating sequence ID, you must
  901. specify countryid=nnn and codepageid=nnn.  Use a valid
  902. country ID and code page ID.  If you want to use the
  903. current locale, specify countryid=-1 and codepageid=
  904. -1.
  905.  
  906. The first 265 bytes of an alternating collating
  907. sequence file contain the definition of a collating
  908. sequence other than the standard ASCII sequence.  If
  909. you want to create an alternate collating sequence
  910. file, generate a file in the format that Table A-3
  911. specifies.
  912.  
  913. Table A-3
  914. Alternate Collating
  915. Sequence File
  916. Format
  917.  
  918. Offset     Length       Description
  919.  
  920. 0            1          Signature byte. This byte
  921.                         should always contain
  922.                         the value ACh.
  923.  
  924. 1            8          An 8-byte name that uniquely
  925.                         identifies the alternate
  926.                         collating sequence to Btrieve.
  927.  
  928. 9          256          A 256-byte table containing
  929.                         the sort value for every
  930.                         character. Store the value for
  931.                         each sort character at the
  932.                         offset corresponding to
  933.                         the character's representation
  934.                         in the ASCII collating
  935.                         sequence.
  936.  
  937.  
  938. For example, to sort the character A as something
  939. other than 41h, store the new sort value at offset 41h
  940. in the table.  For example, assume you want to insert
  941. a character with a 5Dh between the letters U (55h) and
  942. V (56h) in your sequence.  In this case, byte 5Dh in
  943. the sequence should contain the value 56h, and bytes
  944. 56h through 5Ch in the sequence should contain the
  945. values 57h through 5Dh.
  946.  
  947.